home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / dmnet / dmnetsend.z / dmnetsend
Encoding:
Text File  |  2002-10-03  |  7.9 KB  |  133 lines
  1.  
  2.  
  3.  
  4. DDDDMMMMNNNNEEEETTTTSSSSEEEENNNNDDDD((((3333ddddmmmm))))                                                  DDDDMMMMNNNNEEEETTTTSSSSEEEENNNNDDDD((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      dmNetSend, dmNetRecv - send and receive DMbuffers
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ddddmmmmnnnneeeetttt....hhhh>>>>
  13.  
  14.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmNNNNeeeettttSSSSeeeennnndddd((((DDDDMMMMNNNNeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn ccccoooonnnnnnnneeeeccccttttiiiioooonnnn,,,, DDDDMMMMbbbbuuuuffffffffeeeerrrr ddddmmmmbbbbuuuuffff))));;;;
  15.  
  16.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmNNNNeeeettttRRRReeeeccccvvvv((((DDDDMMMMNNNNeeeettttCCCCoooonnnnnnnneeeeccccttttiiiioooonnnn ccccoooonnnnnnnneeeeccccttttiiiioooonnnn,,,, DDDDMMMMbbbbuuuuffffffffeeeerrrr ****ddddmmmmbbbbuuuuffff))));;;;
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      ddddmmmmNNNNeeeettttSSSSeeeennnndddd sends the specified DMbuffer over the open data connection
  20.      specified by _D_M_n_e_t_c_o_n_n_e_c_t_i_o_n.
  21.  
  22.      ddddmmmmNNNNeeeettttRRRReeeeccccvvvv returns a filled DMbuffer from the open data connection
  23.      specified by _D_M_n_e_t_c_o_n_n_e_c_t_i_o_n. The DMbuffer is allocated from the
  24.      DMbufferpool which had been previous registered with the call to
  25.      ddddmmmmNNNNeeeettttRRRReeeeggggiiiisssstttteeeerrrrPPPPoooooooollll or is pre-allocated and passed into dmNetRecv, after a
  26.      call to ddddmmmmNNNNeeeettttRRRReeeeggggiiiisssstttteeeerrrrBBBBuuuuffffffffeeeerrrr ....
  27.  
  28. TTTTIIIIMMMMEEEESSSSTTTTAAAAMMMMPPPPSSSS
  29.      If the caller does not set the MSC associated with the _D_M_b_u_f_f_e_r ,
  30.      ddddmmmmNNNNeeeettttSSSSeeeennnndddd will provide a monotonically increasing value. To avoid
  31.      possible confusion, callers should either _a_l_w_a_y_s set an MSC value, or
  32.      _n_e_v_e_r set one.
  33.  
  34.      ddddmmmmNNNNeeeettttSSSSeeeennnndddd and ddddmmmmNNNNeeeettttRRRReeeeccccvvvv will cooperate in an attempt to make the UST
  35.      value at the receiving end of a network connection equivalent to the UST
  36.      value that was set at the sending end. This is accomplished by converting
  37.      the UST to an equivalent "wall clock" value (via
  38.      ddddmmmmGGGGeeeettttUUUUSSSSTTTTCCCCuuuurrrrrrrreeeennnnttttTTTTiiiimmmmeeeePPPPaaaaiiiirrrr).  This wall clock value is sent to the receiving
  39.      end, which converts it back to an equivalent local UST value.  For this
  40.      to be effective, the system clocks on the two machines must be
  41.      synchronized by some external mechanism, such as _x_n_t_p_d or _t_i_m_e_d.
  42.  
  43.      If the sender sets the UST value to zero, ddddmmmmNNNNeeeettttSSSSeeeennnndddd and ddddmmmmNNNNeeeettttRRRReeeeccccvvvv will
  44.      leave the value undisturbed. This is a convenient way for the sender to
  45.      indicate that the receiver that the clock value is not to be trusted.
  46.  
  47. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  48.      Depending on the underlying transport protocol, ddddmmmmNNNNeeeettttSSSSeeeennnndddd and ddddmmmmNNNNeeeettttRRRReeeeccccvvvv
  49.      may or may not block (see the NNNNOOOOTTTTEEEE below).  They return DM_SUCCESS or
  50.      DM_FAILURE.
  51.  
  52.      ddddmmmmNNNNeeeettttSSSSeeeennnndddd and ddddmmmmNNNNeeeettttRRRReeeeccccvvvv fail if one or more of the following are true:
  53.  
  54.      EEEEIIIINNNNVVVVAAAALLLL         ccccoooonnnnnnnneeeeccccttttiiiioooonnnn is not a valid connection descriptor.
  55.  
  56.      EEEESSSSHHHHUUUUTTTTDDDDOOOOWWWWNNNN      the peer has closed the underlying network connection.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDMMMMNNNNEEEETTTTSSSSEEEENNNNDDDD((((3333ddddmmmm))))                                                  DDDDMMMMNNNNEEEETTTTSSSSEEEENNNNDDDD((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      In addition, ddddmmmmNNNNeeeettttSSSSeeeennnndddd can fail as follows:
  75.  
  76.      EEEEBBBBUUUUSSSSYYYY          insufficient internal resources to send the buffer (only
  77.                     when the underlying transport mechanism is using a DMS
  78.                     fifo; usually indicates that the receiver is not reading
  79.                     quickly enough).
  80.  
  81.      EEEEPPPPIIIIPPPPEEEE          receiver died in the middle of a write system call (dmNet
  82.                     catches SSSSIIIIGGGGPPPPIIIIPPPPEEEE and reports errno as EEEEPPPPIIIIPPPPEEEE).
  83.  
  84.      ddddmmmmNNNNeeeettttRRRReeeeccccvvvv can fail as follows:
  85.  
  86.      EEEEBBBBUUUUSSSSYYYY          no data is available to be read (only when the underlying
  87.                     transport mechanism returns filled DMbuffers via a DMS
  88.                     fifo; currently only DDDDMMMMNNNNEEEETTTT____LLLLOOOOCCCCAAAALLLL).
  89.  
  90.      EEEENNNNOOOOMMMMEEEEMMMM         no DMbuffer could be allocated for the incoming data.
  91.  
  92.      EEEENNNNOOOODDDDAAAATTTTAAAA        end of file reached - no more data available.
  93.  
  94.      EEEERRRRAAAANNNNGGGGEEEE         the buffer allocated from the pool is too small to hold
  95.                     the received data.
  96.  
  97. NNNNOOOOTTTTEEEE
  98.      Depending on the underlying transport mechanism, the exact semantics of
  99.      ddddmmmmNNNNeeeettttSSSSeeeennnndddd and ddddmmmmNNNNeeeettttRRRReeeeccccvvvv will vary. Some transports never block, instead
  100.      returning EEEEBBBBUUUUSSSSYYYY when there are insufficient resources or no waiting data.
  101.      Others block if only some of the data has arrived on the network
  102.      connection, or if the outgoing network connection is too full to deliver
  103.      all of the data into the kernel.  Applications that are concerned about
  104.      timely execution of these routines should use sssseeeelllleeeecccctttt and ddddmmmmNNNNeeeettttDDDDaaaattttaaaaFFFFdddd to
  105.      determine the likelihood that data is ready. It should go without saying
  106.      that they must also carefully check the return and error values. Error
  107.      values are may be obtained through ddddmmmmGGGGeeeettttEEEErrrrrrrroooorrrr
  108.  
  109.      Most applications will want to call these routines in a separate thread.
  110.  
  111. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  112.      dmBufferAllocate(3dm), dmGetUSTCurrentTimePair(3dm), dmNetDataFd(3dm),
  113.      dmNetRegisterPool(3dm), dmNetRegisterBuffer(3dm), select(2), xntpd(1L),
  114.      timed(1M)
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.